---
title: 'Server Manager'
description: 'Dynamic multi-server orchestration for agents'
icon: 'sitemap'
---

The Server Manager enables intelligent orchestration of multiple MCP servers, allowing agents to dynamically discover, connect to, and utilize tools from different servers without loading everything upfront.

## Why Use Server Manager?

When working with multiple MCP servers, you face a challenge: each server can expose dozens of tools, and loading all tools from all servers into your agent's context can be overwhelming and inefficient.

The Server Manager solves this by:

- **Dynamic loading**: Load tools only when needed, not everything upfront
- **Intelligent routing**: Automatically select the right server for each task
- **Context optimization**: Keep agent context focused and efficient
- **Automatic discovery**: Find and connect to the right tools automatically
- **Lifecycle management**: Handle connections and cleanup automatically

<Tip>
**Best for multi-server setups**: If you're connecting to 3+ servers or dealing with 20+ total tools, the Server Manager significantly improves agent performance and context efficiency.
</Tip>

## Architecture Overview

```mermaid
graph TB
    Agent[MCPAgent] --> SM[ServerManager]
    SM --> S1[Web Server]
    SM --> S2[File Server]
    SM --> S3[Database Server]

    SM --> Tools[Dynamic Tools]
```

## Dynamic Tool Loading Process

```mermaid
sequenceDiagram
    Agent->>ServerManager: Connect to server
    ServerManager->>Server: Get tools
    Server->>ServerManager: Return tools
    ServerManager->>Agent: Tools now available
    Agent->>Server: Use tools directly
```

## Getting Started

Enable the Server Manager in your agent:

<CodeGroup>
```typescript TypeScript
import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

// Create client with multiple servers
const client = new MCPClient({
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest']
        },
        filesystem: {
            command: 'uvx',
            args: ['mcp-server-filesystem', '/tmp']
        }
    }
})

// Enable Server Manager
const agent = new MCPAgent({
    llm: new ChatOpenAI({ model: 'gpt-4' }),
    client,
    useServerManager: true  // This is the magic switch!
})
```

```typescript TypeScript
import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

// Create client with multiple servers
const client = new MCPClient({
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest']
        },
        filesystem: {
            command: 'uvx',
            args: ['mcp-server-filesystem', '/tmp']
        }
    }
})

// Enable Server Manager
const agent = new MCPAgent({
    llm: new ChatOpenAI({ model: 'gpt-4' }),
    client,
    useServerManager: true  // This is the magic switch!
})
```
</CodeGroup>

## Tool Discovery Flow

## Management Tools Deep Dive

### Core Server Management

| Tool | Purpose | Example |
|------|---------|---------|
| `list_mcp_servers` | Discovery of available servers and their tools | "What servers do I have access to?" |
| `connect_to_mcp_server` | Activate a server and load its tools | "Connect to the filesystem server" |
| `get_active_mcp_server` | Check current connection status | "Which server am I currently using?" |
| `disconnect_from_mcp_server` | Deactivate server and remove its tools | "Disconnect from current server" |
| `search_mcp_tools` | Semantic search across all server tools | "Find tools for image processing" |

### Smart Tool Search Example

<CodeGroup>
```typescript TypeScript
// Agent automatically discovers and uses the right tools
const result = await agent.run(`
I need to:
1. Find tools for web scraping
2. Connect to the right server
3. Scrape data from https://example.com
4. Save it to a file

Start by searching for relevant tools.
`)
```

```typescript TypeScript
// Agent automatically discovers and uses the right tools
const result = await agent.run(`
I need to:
1. Find tools for web scraping
2. Connect to the right server
3. Scrape data from https://example.com
4. Save it to a file

Start by searching for relevant tools.
`)
```
</CodeGroup>

**Agent Process:**
```mermaid
graph LR
    Search[Search Tools] --> Connect[Connect Server]
    Connect --> Use[Use Tools]
```

## Real-World Use Cases

### 1. Multi-Server Data Pipeline

<CodeGroup>
```typescript TypeScript
const result = await agent.run(`
Create a data pipeline that:
1. Scrapes product data from an e-commerce site
2. Processes and cleans the data
3. Saves it to a CSV file
4. Loads it into a SQLite database

Figure out which servers and tools you need.
`)
```

```typescript TypeScript
const result = await agent.run(`
Create a data pipeline that:
1. Scrapes product data from an e-commerce site
2. Processes and cleans the data
3. Saves it to a CSV file
4. Loads it into a SQLite database

Figure out which servers and tools you need.
`)
```
</CodeGroup>

**Server Flow:**
```
playwright → filesystem → database
    ↓            ↓          ↓
 scraping → save CSV → load data
```

### 2. Content Creation Workflow

<CodeGroup>
```typescript TypeScript
const result = await agent.run(`
I want to:
1. Search for trending topics online
2. Generate an image based on the topic
3. Write a blog post about it
4. Save everything to files

What tools do I need for this?
`)
```

```typescript TypeScript
const result = await agent.run(`
I want to:
1. Search for trending topics online
2. Generate an image based on the topic
3. Write a blog post about it
4. Save everything to files

What tools do I need for this?
`)
```
</CodeGroup>

## Performance Benefits

The Server Manager provides focused tool access:

- **Without Server Manager**: All 100+ tools from all servers loaded at once, overwhelming the model
- **With Server Manager**: Only 5-15 relevant tools from the active server, providing clear focus

##  Core Features

The Server Manager provides these powerful capabilities:

- **Dynamic Tool Addition**: Server tools automatically added with full schemas
- **Real-time Updates**: Tool list updates immediately when connecting/disconnecting
- **Clean Architecture**: Direct tool access with proper schemas
- **Model Understanding**: Tools come with native schemas and validation
- **Smart Logging**: Detailed insights into tool changes and server status

## Complete Example

<CodeGroup>
```typescript TypeScript
import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

async function demoServerManager() {
    // Multi-server configuration
    const client = new MCPClient({
        mcpServers: {
            web: { command: 'npx', args: ['@playwright/mcp@latest'] },
            files: { command: 'uvx', args: ['mcp-server-filesystem', '/tmp'] },
            database: { command: 'uvx', args: ['mcp-server-sqlite'] }
        }
    })

    // Agent with Server Manager
    const agent = new MCPAgent({
        llm: new ChatOpenAI({ model: 'gpt-4' }),
        client,
        useServerManager: true,
        verbose: true  // See the magic happen!
    })

    // Complex multi-server task
    const result = await agent.run(`
    I need to build a complete data collection system:

    1. First, show me what servers and tools are available
    2. Scrape product information from https://example-store.com
    3. Clean and structure the data
    4. Save it as both JSON and CSV files
    5. Load the data into a SQLite database
    6. Generate a summary report

    Guide me through each step and show me how you discover and use the right tools.
    `)

    console.log('Task completed!')
    console.log(result)

    await client.closeAllSessions()
}

demoServerManager().catch(console.error)
```

```typescript TypeScript
import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

async function demoServerManager() {
    // Multi-server configuration
    const client = new MCPClient({
        mcpServers: {
            web: { command: 'npx', args: ['@playwright/mcp@latest'] },
            files: { command: 'uvx', args: ['mcp-server-filesystem', '/tmp'] },
            database: { command: 'uvx', args: ['mcp-server-sqlite'] }
        }
    })

    // Agent with Server Manager
    const agent = new MCPAgent({
        llm: new ChatOpenAI({ model: 'gpt-4' }),
        client,
        useServerManager: true,
        verbose: true  // See the magic happen!
    })

    // Complex multi-server task
    const result = await agent.run(`
    I need to build a complete data collection system:

    1. First, show me what servers and tools are available
    2. Scrape product information from https://example-store.com
    3. Clean and structure the data
    4. Save it as both JSON and CSV files
    5. Load the data into a SQLite database
    6. Generate a summary report

    Guide me through each step and show me how you discover and use the right tools.
    `)

    console.log('Task completed!')
    console.log(result)

    await client.closeAllSessions()
}

demoServerManager().catch(console.error)
```
</CodeGroup>

The Server Manager transforms your MCP agent from a static tool user into an intelligent, adaptive assistant that can dynamically discover and utilize the perfect tools for any task!

## Bring Your Own Server Manager

For ultimate control, you can create your own server manager. By implementing the `BaseServerManager` abstract class, you can define custom logic for tool discovery, dynamic tool creation, or integration with other systems. The server manager's primary role is to provide tools **to the agent**. These can be management tools for connecting to external MCP servers, or, as shown below, custom tools that operate entirely within the agent's environment without needing an external server.

Here’s a minimal example of a custom server manager that provides a single, hard-coded tool directly to the agent.

